feat: replace ref-based messages with component-based message bubbles by avoidwork · Pull Request #555 · avoidwork/madz

avoidwork · 2026-07-18T03:06:39Z

Summary

Replace the ref-based message array architecture in the TUI with a component-based system where each message is a standalone MessageBubble component managing its own state.

Changes

Created src/tui/messageBubble.js: MessageBubble component with internal state management (content, streaming, toolCallDisplay, reasoningContent). Exposes update() method for streaming events.
Created src/tui/messageList.js: Manages array of MessageBubble instances with addMessage(), updateMessage(), clear() methods. Handles MAX_RENDER_MESSAGES windowing and scroll-to-bottom.
Updated src/tui/conversationPanel.js: Simplified to thin wrapper rendering MessageList.
Updated src/tui/app.js: Removed messagesRef, forceRender, renderCount. Uses MessageList instance.
Updated tests for new component API.

Motivation

The current architecture uses messagesRef (mutable array) + forceRender (useState counter) + array spreading + useEffect scroll-to-bottom. This fights React's model and causes memory leaks, unnecessary re-renders, and unreliable scroll management.

Fixes #541

Replace the ref-based message array with modular MessageBubble and MessageList components for better state management and readability. - Add messageBubble.js: memo-wrapped component with imperative update() API via useImperativeHandle for streaming content updates - Add messageList.js: container managing bubble instances, imperative APIs (addMessage, updateMessage, clear, setMessages), scroll throttle, and auto-scroll behavior - Refactor conversationPanel.js: thin wrapper delegating to MessageList - Refactor app.js: remove messages array state, forceRender, and manual scroll logic, delegate entirely to messageListRef imperatives

Implement pub/sub architecture where each MessageBubble subscribes to its own topic (msg-{id}). MessageList publishes streaming updates that bubble catches and appends its own chunks array, triggering independent re-renders without parent re-render. This solves the streaming gap bug where app.js called updateMessage() but the bubble never updated mid-stream. - Add createPubSub() factory in messageBubble.js for testable pub/sub - Add PubSubContext for React context propagation - Replace forceRenderKeyRef in MessageList with topicsRef + subscribe/publish - MessageBubble uses useContext + useEffect subscription with dedup - Add 12 pubsub unit tests and 11 messageListApi simulation tests

avoidwork · 2026-07-18T03:38:29Z

Pub/sub fix committed (5a27498):

MessageBubble now uses to subscribe to its own topic ()
Each pub/sub update appends to the bubble's state → re-renders just that bubble
Deduplication: identical consecutive content chunks are skipped (no duplicate renders)
PubSubContext provided by MessageList via context, scoped to this tree only
createPubSub() factory exported for standalone testing (12 pubsub tests + 11 messageListApi simulation tests)

This solves the streaming gap bug where called but the bubble never updated mid-stream because mutating refs doesn't trigger React reconciliation.

Spread syntax requires children to be an array, but React children can be a single element, null, or other non-array types. Wrap with toArray() to guarantee an iterable array before spreading.

The TUI message bubble refactoring was implemented with a pub/sub topic system instead of the original forwardRef + useImperativeHandle ref callback approach. This simplifies the architecture by eliminating the need for MessageList to track bubble instance refs. - Replaced ref callback pattern with unique pub/sub topics per message - MessageBubble uses chunk accumulation via useState instead of streamingId - Scroll ref accessed via getScrollRef() instead of prop forwarding - Added PubSub API requirements and scenarios to specs - Updated design doc with pub/sub rationale and trade-offs

Remove the inline memo-wrapped MessageBubble component and its associated imports from conversationPanel.js. The module now delegates entirely to the component-based MessageList with pub/sub. Update conversationPanel.test.js and tui.test.js to remove stale renderMessages tests and replace them with MessageList integration tests. - Removed MessageBubble memo wrapper and related imports - Removed renderMessages utility and associated tests - 302 lines deleted, 61 added

…to conversationPanel test

avoidwork · 2026-07-18T15:35:59Z

New fix: preserve conversation history on stream interruption

When a user sends a message while the agent is streaming, handleInterrupt() is called (app.js:109) to abort the old stream. The abort caused the old dispatch to throw AbortError, and the catch handler at line 504 was calling messageListRef.current?.clear() — wiping the entire conversation.

This removes the clear() from the AbortError handler so the history stays intact when interrupts occur.

…ge-bubbles

avoidwork · 2026-07-18T15:45:56Z

Post-Audit Results

Goal Fulfillment

Replace ref-based message array with component-based MessageBubble
Each message manages its own chunk state via pub/sub
MessageList owns scroll management (ScrollView, throttle, resize, user scroll detection)
ConversationPanel simplified to thin wrapper
app.js uses imperative API (addMessage/updateMessage) instead of array mutations

Spec Compliance

delta spec component-message-bubbles/spec.md: 100% of required capabilities implemented
delta spec tui-scroll-view/spec.md: 100% of scroll requirements implemented
No spec requirements were violated

Quality Checks

All 1002 tests pass (including 23 new: 11 messageListApi, 12 pubsub)
Lint clean (oxlint + oxfmt)
Coverage maintained at 86.97%
No regressions in existing functionality
Application starts without crashing

Deviations from Plan

The original plan did not mention fixing the abort/handInterrupt history-clear bug
This was discovered during the feature work and fixed in commit 524681b

Risks / Known Issues

Delta specs were archived with --skip-specs due to header mismatches (MODIFIED ops couldn't match renamed main spec headers). The main specs may need manual reconciliation to reflect the new architecture.
The archive has minor validation warnings in proposal.md (non-blocking: SHALL/must keyword issues)

- Create openspec/specs/component-message-bubbles/spec.md from archived delta (all ADDED, no header mismatch issues) - Reconcile openspec/specs/tui-scroll-view/spec.md: replace all ConversationPanel scroll responsibilities with MessageList (ownership moved from data-driven to imperative ref-based) - Update archived delta .openspec.yaml with reconciliation timestamp

avoidwork · 2026-07-18T15:54:35Z

Delta Spec Reconciliation Note

The archived delta specs (openspec archive) were unable to auto-sync because:

component-message-bubbles: MODIFIED header for "No ref callback pattern" didn't match any existing main spec header (it was a completely new spec)
tui-scroll-view: MODIFIED headers said "Conversation panel uses ScrollView" but the actual implementation moved ownership to MessageList, so the delta headers didn't match the archived main spec verbatim

Reconciliation done on this branch (commit 056a9e7):

openspec/specs/component-message-bubbles/spec.md — created from the archived delta (all requirements were ADDED, no reconciliation needed)
openspec/specs/tui-scroll-view/spec.md — updated to reflect actual implementation: "ConversationPanel" → "MessageList" for all scroll ownership, keyboard input, resize handling, and auto-scroll management. Added "MessageList owns auto-scroll management" requirement. Updated app.js requirement to reflect imperative message management instead of scroll state management.

The archived delta files are preserved in openspec/changes/archive/2026-07-18-replace-ref-based-messages-with-component-message-bubbles/specs/ with reconciliation notes.

avoidwork · 2026-07-18T15:58:23Z

Closes #541

avoidwork added 2 commits July 17, 2026 22:29

feat: replace ref-based messages with component-based message bubbles

69881fd

avoidwork mentioned this pull request Jul 18, 2026

feat: replace ref-based messages with component-based message bubbles #541

Closed

avoidwork added 2 commits July 17, 2026 23:10

fix: remove unused messages variable in MessageList

4daa932

avoidwork added 9 commits July 17, 2026 23:40

fix(tui): use React.Children.toArray in PubSubProvider

54564bf

Spread syntax requires children to be an array, but React children can be a single element, null, or other non-array types. Wrap with toArray() to guarantee an iterable array before spreading.

docs: add pub/sub API test documentation to createPubSub JSDoc

e836d2a

docs: mark all automated tasks complete in tasks.md; add legacy note …

1b20c67

…to conversationPanel test

docs: mark manual verification task 9.5 complete

de8c55b

fix: trigger auto-scroll on message add and update

2264238

fix: preserve conversation history on stream interruption

524681b

chore: archive change replace-ref-based-messages-with-component-messa…

ec33c62

…ge-bubbles

avoidwork merged commit f1ec04f into main Jul 18, 2026
2 checks passed

avoidwork deleted the feat/replace-ref-based-messages-with-component-message-bubbles branch July 18, 2026 15:59

avoidwork mentioned this pull request Jul 18, 2026

chore: release v1.30.0 #556

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: replace ref-based messages with component-based message bubbles#555

feat: replace ref-based messages with component-based message bubbles#555
avoidwork merged 15 commits into
mainfrom
feat/replace-ref-based-messages-with-component-message-bubbles

avoidwork commented Jul 18, 2026

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

avoidwork commented Jul 18, 2026 •

edited

Loading

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

avoidwork commented Jul 18, 2026

Summary

Changes

Motivation

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

avoidwork commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New fix: preserve conversation history on stream interruption

Uh oh!

avoidwork commented Jul 18, 2026

Post-Audit Results

Goal Fulfillment

Spec Compliance

Quality Checks

Deviations from Plan

Risks / Known Issues

Uh oh!

avoidwork commented Jul 18, 2026

Delta Spec Reconciliation Note

Uh oh!

avoidwork commented Jul 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

avoidwork commented Jul 18, 2026 •

edited

Loading